Skip to content

docs: Update upgrade guide to 4.0#603

Merged
developerjamiu merged 7 commits into
mainfrom
chore/update-upgrade-guide-to-4
Jul 7, 2026
Merged

docs: Update upgrade guide to 4.0#603
developerjamiu merged 7 commits into
mainfrom
chore/update-upgrade-guide-to-4

Conversation

@Zfinix

@Zfinix Zfinix commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Summary

Updates the upgrade guide from 3.5 to 4.0 (title, headings, prose, version pins, and the migration tag). The 3.4 from-version and the Dart SDK constraints are left unchanged.

The filename and URL slug keep upgrade-to-three-five so the existing inbound links from the legacy-auth guide don't break. Happy to rename the file in a follow-up if we want the URL to match.

Part of #584

@Swiftaxe Swiftaxe left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good!

One thing left: The guide is missing how to set up the MCP servers. This is done automatically when creating new serverpod projects, but when upgrading it is currently manual, unless we offer a command to run in the CLI.

It says: "Some editors, like Cursor, require enabling the MCP server in their settings.", but the user gets no help in how to set this up for their IDE, and has to research this themselves.

@Swiftaxe

Copy link
Copy Markdown
Collaborator

A new command was merged yesterday, serverpod create . which improves the upgrading experience.

For instance, upgrading a project without migrations will show the Database and IDE options in the TUI.
Upgrading a project that already contains migrations will only show the IDE options in the TUI.

The TUI will then give options to select IDE which then install skills, and configure MCP.

serverpod/serverpod#5341

@Zfinix

Zfinix commented Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

Looks good!

One thing left: The guide is missing how to set up the MCP servers. This is done automatically when creating new serverpod projects, but when upgrading it is currently manual, unless we offer a command to run in the CLI.

It says: "Some editors, like Cursor, require enabling the MCP server in their settings.", but the user gets no help in how to set this up for their IDE, and has to research this themselves.

Can we add this to a new PR

Comment thread docs/11-upgrading/01-upgrade-to-three-five.md Outdated
Comment thread docs/11-upgrading/01-upgrade-to-three-five.md Outdated
@developerjamiu

Copy link
Copy Markdown
Contributor

Suggestion: Since 4.0 is confirmed, let's rename the file to match: 01-upgrade-to-three-five.md01-upgrade-to-four.md (follows the upgrade-to-<version> pattern in this folder).

Three internal links point at the old slug and would fail the build, so update them in the same commit:

  • 03-migrate-from-legacy-auth.md lines 12 and 297: ./upgrade-to-three-five./upgrade-to-four
  • 06-concepts/cli/commands/upgrade/_upgrade.md line 5: .../01-upgrade-to-three-five.md.../01-upgrade-to-four.md

The URL hasn't been shared widely, so a redirect entry isn't needed.

Zfinix and others added 2 commits July 6, 2026 16:54
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
Comment thread docs/11-upgrading/01-upgrade-to-three-five.md Outdated
Comment thread docs/11-upgrading/01-upgrade-to-four.md Outdated

@developerjamiu developerjamiu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two small changes and you can merge.

@Zfinix Zfinix requested a review from developerjamiu July 6, 2026 20:58
@developerjamiu developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 7, 2026
@developerjamiu developerjamiu merged commit 898ef9b into main Jul 7, 2026
4 checks passed
@developerjamiu developerjamiu deleted the chore/update-upgrade-guide-to-4 branch July 7, 2026 05:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants